/*
 * Copyright 2006 Matt Jensen
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations under the License.
 */
package org.spectaql;

/**
 * <p>
 * <code>SpectaqlContextBuilder</code> defines the public interface to an object which is used to create and configure
 * {@link SpectaqlContext} instances.
 * </p>
 * <p>
 * Clients can obtain an instance implementing this interface by calling {@link Spectaql#buildContext()}.
 * </p>
 */
public interface SpectaqlContextBuilder
{
    /**
     * <p>
     * Create a {@link SpectaqlContext} instance from the applied configuration.
     * </p>
     *
     * @return {@link SpectaqlContext} instance.
     */
    SpectaqlContext create();

    /**
     * <p>
     * Set the {@link ProxyInstantiationStrategy} through which instrumented entities will be created.
     * </p>
     * <p>
     * If this property is not supplied, a default implementation will be used. 
     * </p>
     *
     * @param strategy proxy instantiation strategy.
     * @return {@link SpectaqlContextBuilder} this builder instance.
     * @throws IllegalStateException if the property has already been set.
     */
    SpectaqlContextBuilder setProxyInstantiationStrategy(ProxyInstantiationStrategy strategy)
            throws IllegalStateException;

    /**
     * <p>
     * Set the {@link PersistenceAdapter} instance through which O/R mapping information will be obtained.
     * </p>
     *
     * @param source the persistence metadata source.
     * @return {@link SpectaqlContextBuilder} this builder instance.
     * @throws IllegalStateException if the property has already been set.
     */
    SpectaqlContextBuilder setPersistenceAdapter(PersistenceAdapter source) throws IllegalStateException;
}
